Formation Quarto

Parcours de formation R perfectionnement SSP

Michaël Delorme

SSP/DéMéSIS

2025-02-07

Pré-requis techniques

library(dplyr)   # manip. données
library(ggplot2) # graphiques
library(sf)      # carto
library(leaflet) # carto
library(gt)

# un theme ggplot utilisant la police Marianne
theme_masa <- function(...) {
  theme_grey(...) %+replace%
    theme(
      text = element_text(family = "Marianne"))
}

Introduction

Mise en garde

DIAPORAMA EN COURS DE CONSTRUCTION

Objectifs

  • Intérêt des publications reproductibles
  • Découvrir la versatilité de Quarto
  • Réaliser un document simple à complexe

Quarto

Un système de publication

  • multi-format
    • HTML (rapports, livres, présentations)
    • PDF
    • Appli web (statique/Shiny) : blog, site, tableau de bord
    • MS Word

Figure 1: Principe de fonctionnement (source RStudio)

Avantages

  • intégration avec R
  • reproductibilité
  • versionnement avec git

Inconvénients

  • syntaxe (markdown)
  • génération

Sur CERISE

Un package {quarto} et un binaire quarto.

quarto check install
quarto check knitr

Syntaxe et structure

---
title: "Litany against fear"
author: "Bene Gesserit"
---

I must not fear. *Fear is the mind-killer*. Fear is the little-death that
brings total obliteration. 

```{python}
import numpy as np
np.exp(np.pi * complex(0, 1)) + 1
```

**I will face my fear.** I will permit it to pass over me and through me.

```{r}
somme <- sum(1:10)
```

And when it has gone past I will turn the `{r} somme` inner eye to see its 
path. Where the fear has gone there will be nothing. Only I will remain.

markdown

Un langage balisé simple

doc

chunks

Le code exécutable est intégré dans un chunk (bloc) :

```{r}
#| label: mon-chunk
#| warning: false

1+1
```

doc

YAML

  • en-tête de configuration
  • bloc entre ---
  • a minima : title:
  • variable selon les formats

Rendu

quarto render mon_document.qmd

Ctrl k ou (ou )

À vous de jouer

Exercice 1 et Exercice 2 : découvrir l’interface et produire un document simple

Éléments

Texte

  • 2 retours à la ligne pour faire un paragraphe
  • 2 espaces et 1 retour à la ligne pour un saut de ligne
  • * ou _ pour mettre en *italique* ou en **gras**
  • [un lien](https://www.example.org/)un lien
  • une portion de texte peut être stylée en vert avec [vert]{style="color:darkgreen"}
  • mais du HTML est aussi possible <span style="color:red">rouge</span> pour mettre en rouge

doc

Titres

Préfixer le titre avec #, ## ou ### pour avoir les titres de niveau 1, 2 ou 3, etc..

#### Titre de niveau 4

Titre de niveau 4

Listes

- Atréides
  - Leto
  - Jessica
  - Paul
- Harkonnen
  - Vladimir
  - Rabban
  - Feyd-Rautha

ou

- Atréides
  * Leto
  * Jessica
  * Paul
- Harkonnen
  * Vladimir
  * Rabban
  * Feyd-Rautha
  • Atréides
    • Leto
    • Jessica
    • Paul
  • Harkonnen
    • Vladimir
    • Rabban
    • Feyd-Rautha
- Atréides
  - Leto
  - Jessica  
    2 espace + nouvelle ligne + aligner pour 
    ajouter du texte dans les items
  - Paul
- Harkonnen
  - Vladimir
  - Rabban
  - Feyd-Rautha
  • Atréides
    • Leto
    • Jessica
      2 espace + nouvelle ligne + aligner pour ajouter du texte dans les items
    • Paul
  • Harkonnen
    • Vladimir
    • Rabban
    • Feyd-Rautha

Liens

[Texte du lien](https://fr.wikipedia.org/wiki/Arrakis)

Texte du lien

Images

![Fremen](images/images/dune_book.jpg)

A sand worm on Arrakis

Figure 2: Fremen

![Fremen](images/images/dune_book.jpg "Shai-hulud"){#fig-dune fig-alt="A sand worm on Arrakis"}

Exercice 3 : formater du texte

Renvois

(cross-references)

Un lien automatique est créé si on indique @fig-dune ; il nous renvoie à Figure 2.

Les noms des types affichés peuvent être modifiés dans l’en-tête :

---
crossref:
  fig-prefix: figure
  fig-title:  Figure
  tbl-prefix: tableau
  tbl-title:  Tableau
  title-delim: " &ndash; "
---

Code

iris |> 
  glm(Sepal.Length ~ Sepal.Width, data = _)

Call:  glm(formula = Sepal.Length ~ Sepal.Width, data = iris)

Coefficients:
(Intercept)  Sepal.Width  
     6.5262      -0.2234  

Degrees of Freedom: 149 Total (i.e. Null);  148 Residual
Null Deviance:      102.2 
Residual Deviance: 100.8    AIC: 372

Options de bloc de code

  • exécution :
  • #| eval: exécuter le code
  • #| echo: afficher le code
  • nommage :
  • #| label: identifiant du chunk
  • #| fig-cap: légende du bloc

Outils

Si on a #| echo: true l’utilisateur voit le code mais on peut ajouter des outils pour l’utilisateur pour qu’il affiche ou cache les chunks avec, dans l’en-tête YAML :

format: 
  html:
    code-fold: true
    code-tools: true

Sorties de code

  • texte, avec :
    • #| results: markup ou
    • cat() et #| results: asis
  • tableaux
  • images
  • éléments interactifs

Tableaux

iris |> 
  summarise(.by = Species,
            moy_sepales = sum(Sepal.Length))
     Species moy_sepales
1     setosa       250.3
2 versicolor       296.8
3  virginica       329.4

Avec

format:
  html:
    df-print: kable
iris |> 
  summarise(.by = Species,
            moy_sepales = sum(Sepal.Length)) |> 
  knitr::kable()
Iris (kable)
Species moy_sepales
setosa 250.3
versicolor 296.8
virginica 329.4

doc

ou avec {gt}

iris |> 
  summarise(.by = Species,
            moy_sepales = sum(Sepal.Length)) |> 
  gt()
Iris (gt)
Species moy_sepales
setosa 250.3
versicolor 296.8
virginica 329.4

Notes de pied de page

Les notes se construisent en ajoutant un [^1] dans le texte, avec le 1 pouvant être une numérotation (pas obligatoirement dans l’ordre) ou tout autre mot clé. La note est ensuite introduite avec le même symbole dans un nouveau paragraphe :

[^1]: texte de la note

C’est normalement facile1 à faire si on se rappelle de la syntaxe.

Graphiques

ggplot(iris, aes(Petal.Length, 
                 Petal.Width, 
                 color = Species)) +
  geom_point() +
  theme_masa()
Figure 3: Iris

Taille d’image dans Quarto (Arel-Bundock, 2024)

Cartes

"~/CERISE/03-Espace-de-Diffusion/000_Referentiels/0040_Geo/IGN/adminexpress/adminexpress_cog_simpl_000_2024.gpkg" |> 
  read_sf(layer = "region") |> 
  leaflet() |>
  addTiles() |> 
  addPolygons()
Figure 4: Exemple Leaflet

Équations

Syntaxe Latex entre des $ (inline) ou $$ (bloc).

$\sigma = \sqrt{\frac{1}{N} \sum_{i=1}^N (x_i - \mu)^2},\text{ où } \mu = \frac{1}{N} \sum_{i=1}^N x_i$

\[\sigma = \sqrt{\frac{1}{N} \sum_{i=1}^N (x_i - \mu)^2},\text{ où } \mu = \frac{1}{N} \sum_{i=1}^N x_i\] doc

Citations/bibliographie

Avec Zotero et l’extension Better BibTeX pour auto-exporter en BibTeX la collection quand elle est modifiée.

Préciser le fichier utilisé en en-tête, puis utilisation des identifiants du fichier BibTex.

---
title: "Mon document"
bibliography: formation_quarto.bib
---

Comme le dit @rdevelopmentcoreteamLanguageEnvironmentStatistical2010 :

> Lorem ipsum dolor sit amet[@rstudioGuide2024], consectetur adipiscing elit

Comme le dit R Development Core Team (2010) :

Lorem ipsum dolor sit amet (RStudio, 2024), consectetur adipiscing elit

La bibliographie est directement générée :

  • en fin de document ou

  • après un <div> identifié avec #refs ex. :

    ## Références
    ::: {#refs}
    :::

doc

Libellés

(Callout)

Les “libellés” permettent de mettre en exergue des informations complémentaires.

:::{.callout-note}
Il existe cinq types de libellés : 
`note`, `tip`, `warning`, `caution` et `important`.
:::

Note

Il existe cinq types de : note, tip, warning, caution et important.

doc

Fonctionnalités avancées

Cache

doc

Crosstalk

doc

Dashboards

doc

Marque de l’État

Typographie Marianne

Pour textes et graphiques (Service d’information du gouvernement, 2020)

  • Installer {ragg}, {systemfonts} et {textshaping}

  • Dans l’en-tête yaml du document Quarto :

    ---
    mainfont: Marianne
    knitr:
      opts_chunk: 
        dev: "ragg_png"
    ---

Couleurs

Références

Arel-Bundock V. Consistent Figures in Quarto. Vincent Arel-Bundock. juillet 2024. Disponible sur : < https://arelbundock.com/posts/quarto_figures/index.html >
Canouil M. Awesome-Quarto. janvier 2025. Disponible sur : < https://github.com/mcanouil/awesome-quarto >
Choe J. Setting up and Debugging Custom Fonts. June Choe. juin 2021. Disponible sur : < https://yjunechoe.github.io/posts/2021-06-24-setting-up-and-debugging-custom-fonts/ >
Heiss A. Working with R, Cairo Graphics, Custom Fonts, and Ggplot. Andrew Heiss. avril 2023. Disponible sur : < https://www.andrewheiss.com/blog/2017/09/27/working-with-r-cairo-graphics-custom-fonts-and-ggplot/ > (consulté le 21 janvier 2025)
R Development Core Team. R: A Language and Environment for Statistical Computing. 2010. Disponible sur : < http://www.R-project.org/ >
RStudio. Guide. Quarto. 2024. Disponible sur : < https://quarto.org/docs/guide/ >
Service d’information du gouvernement. Charte graphique de l’État. [s.l.] : République française, 2020. Disponible sur : < https://www.gouvernement.fr/marque-Etat >